<!DOCTYPE html>
<html>
<head>
<title>Weiran ECMAScript Applications Framework</title>
<link rel=stylesheet type=text/css href=./style.css>
</head>

<body>

<div class=leftbar>
    <h1>Weiran</h1>
    <p>ECMAScript<br />Applications Framework</p>
    <p>Version: 1.2</p>
    <ul>
	<li><a href=Weiran.html>Weiran</a></li>
	<li><a href=Weiran.Array.html>Weiran.Array</a></li>
	<li><a href=Weiran.Buffer.html>Weiran.Buffer</a></li>
	<li><a href=Weiran.Class.html>Weiran.Class</a></li>
	<li><a href=Weiran.Date.html>Weiran.Date</a></li>
	<li><a href=Weiran.DB.html>Weiran.DB</a></li>
	<li><a href=Weiran.Event.html>Weiran.Event</a></li>
	<li>Weiran.Events<ul>
	    <li><a href=#Weiran.Events>Weiran.Events</a></li>
	    <li><a href=#.BROWSER_EVENTS>.BROWSER_EVENTS</a></li>
	    <li><a href=#.fallThrough>.fallThrough</a></li>
	    <li><a href=#.includeXY>.includeXY</a></li>
	    <li><a href=#.extensions>.extensions</a></li>
	    <li><a href=#.destroy>.destroy</a></li>
	    <li><a href=#.register>.register</a></li>
	    <li><a href=#.unregister>.unregister</a></li>
	    <li><a href=#.on>.on</a></li>
	    <li><a href=#.un>.un</a></li>
	    <li><a href=#.remove>.remove</a></li>
	    <li><a href=#.triggerEvent>.triggerEvent</a></li>
	    <li><a href=#.clearMouseCache>.clearMouseCache</a></li>
	</ul></li>
	<li><a href=Weiran.Function.html>Weiran.Function</a></li>
	<li><a href=Weiran.JSON.html>Weiran.JSON</a></li>
	<li><a href=Weiran.Lang.html>Weiran.Lang</a></li>
	<li><a href=Weiran.Number.html>Weiran.Number</a></li>
	<li><a href=Weiran.String.html>Weiran.String</a></li>
	<li><a href=Weiran.GRUB.html>GRUB Mechanism</a></li>
    </ul>
    <p>
        Copyright &copy; All<span>i</span>dylls<br />
        2011 - 2012
    </p>
</div>

<div class=content>

<div class=reftitle>Weiran.Events</div>
<p>Class contains utility functions for arbitrary event handling.</p>

<a name=Weiran.Events></a>
<h3><code>Weiran.Events(obj, element, fall, options)</code></h3>
<p><b>Constructor</b></p>
<p>
    <b>Parameters: </b><br />
    <span class=parameters>obj</span> - <code>object</code>, the js object to which this Events object is being added<br />
    <span class=parameters>element</span> - <code>DOMElement</code>, a DOM element to respond to browser events<br />
    <span class=parameters>fall</span> - <code>boolean</code>, allow events to fall through after these have been handled?<br />
    <span class=parameters>options</span> - <code>object</code>, options for the events instance
</p>
<p><b>Returns: </b><code>object</code></p>
<p>Construct an instance of <code>Weiran.Events</code>.</p>

<a name=.BROWSER_EVENTS></a>
<h3><code>.BROWSER_EVENTS</code></h3>
<p><b>Constant: </b><code>array</code></p>
<p>Supported browser events:</p>
<ul>
<li>mouseover</li>
<li>mouseout</li>
<li>mousedown</li>
<li>mouseup</li>
<li>mousemove</li>
<li>click</li>
<li>dblclick</li>
<li>rightclick</li>
<li>dblrightclick</li>
<li>resize</li>
<li>focus</li>
<li>blur</li>
<li>touchstart</li>
<li>touchmove</li>
<li>touchend</li>
<li>keydown</li>
</ul>

<a name=.fallThrough></a>
<h3><code>.fallThrough</code></h3>
<p><b>Property: </b><code>boolean</code></p>
<p>Determine whether event was propagated fall through.</p>

<a name=.includeXY></a>
<h3><code>.includeXY</code></h3>
<p><b>Property: </b><code>boolean</code></p>
<p>Should the .xy property automatically be created for browser mouse events?</p>

<a name=.extensions></a>
<h3><code>.extensions</code></h3>
<p><b>Property: </b><code>object</code></p>
<p>Event extensions registered with this instance. Keys are
    event types, values are <code>Weiran.Events.*</code> extension instances or
    <code>boolean</code> for events that an instantiated extension provides in
    addition to the one it was created for.</p>

<p>Extensions create an event in addition to browser events, which usually
    fires when a sequence of browser events is completed. Extensions are
    automatically instantiated when a listener is registered for an event
    provided by an extension.</p>

<p>Extensions are created in the <code>Weiran.Events</code> namespace using
    <code>Weiran.Class</code>, and named after the event they provide.
    The constructor receives the target <code>Weiran.Events</code> instance as
    argument. Extensions that need to capture browser events before they
    propagate can register their listeners events using <code>.register</code>, with
    <code>{extension: true}</code> as 4th argument.</p>

<p>If an extension creates more than one event, an alias for each event
    type should be created and reference the same class. The constructor
    should set a reference in the target's extensions registry to itself.</p>

<p>Below is a minimal extension that provides the "foostart" and "fooend"
    event types, which replace the native "click" event type if clicked on
    an element with the css class "foo":

<p><code><pre>
    Weiran.Events.foostart = Weiran.Class({
        initialize: function(target) {
            this.target = target;
            this.target.register("click", this, this.doStuff, {extension: true});
            // only required if extension provides more than one event type
            this.target.extensions["foostart"] = true;
            this.target.extensions["fooend"] = true;
        },
        
        destroy: function() {
            var target = this.target;
            target.unregister("click", this, this.doStuff);
            delete this.target;
            // only required if extension provides more than one event type
            delete target.extensions["foostart"];
            delete target.extensions["fooend"];
        },
        
        doStuff: function(evt) {
            var propagate = true;
            if (Weiran.Event.element(evt).className === "foo") {
                propagate = false;
                var target = this.target;
                target.triggerEvent("foostart");
                window.setTimeout(function() {
                    target.triggerEvent("fooend");
                }, 1000);
            }
            return propagate;
        }
    });
    
    // only required if extension provides more than one event type
    Weiran.Events.fooend = Weiran.Events.foostart;</pre></code></p>

<a name=.destroy></a>
<h3><code>.destroy()</code></h3>
<p><b>Instance method</b></p>
<p>
    <b>Parameters:</b>
</p>
<p><b>Returns: </b><code>undefined</code></p>
<p>Destroy this instance.</p>

<a name=.register></a>
<h3><code>.register(type, obj, func, priority)</code></h3>
<p><b>Instance method</b></p>
<p>
    <b>Parameters: </b><br />
    <span class=parameters>type</span> - <code>string</code>, name of the event to register<br />
    <span class=parameters>obj</span> - <code>object</code>, the object to bind the context to for the callback, defaults to <code>this.object</code><br />
    <span class=parameters>func</span> - <code>function</code>, the callback function, if no callback is specified, this function does nothing<br />
    <span class=parameters>priority</span> - <code>boolean</code>, if true, adds the new listener to the front of the events queue, defaults to false
</p>
<p><b>Returns: </b><code>undefined</code></p>
<p>Register an event on the events object.
    When the event is triggered, the 'func' function will be called, in the context of 'obj'.</p>
<p>Valid options for priority is extension, if true, eg: <code>{extension: true}</code>, 
    then the event will be registered as extension event.
    Extension events are handled before all other events.</p>

<a name=.unregister></a>
<h3><code>.unregister(type, obj, func)</code></h3>
<p><b>Instance method</b></p>
<p>
    <b>Parameters:</b><br />
    <span class=parameters>type</span> - <code>string</code>, name of the event to unregister<br />
    <span class=parameters>obj</span> - <code>object</code>, the object to bind the context to for the callback, defaults to <code>this.object</code><br />
    <span class=parameters>func</span> - <code>function</code>, the callback function
</p>
<p><b>Returns: </b><code>undefined</code></p>
<p>Unregister an event.</p>

<a name=.on></a>
<h3><code>.on(obj)</code></h3>
<p><b>Instance method</b></p>
<p>
    <b>Parameters: </b><br />
    <span class=parameters>obj</span> - <code>object</code>
</p>
<p><b>Returns: </b><code>undefined</code></p>
<p>Convenience method for registering listeners with a common scope.
     Internally, this method calls <code>this.register</code> as shown in the examples below.</p>
<p>Examples:</p>
<p><code><pre>
    // register a single listener for the "loadstart" event
    events.on({"loadstart": loadStartListener});
    
    // this is equivalent to the following
    events.register("loadstart", undefined, loadStartListener);
    
    // register multiple listeners to be called with the same `this` object
    events.on({
        "loadstart": loadStartListener,
        "loadend": loadEndListener,
        scope: object
    });
    
    // this is equivalent to the following
    events.register("loadstart", object, loadStartListener);
    events.register("loadend", object, loadEndListener);</pre></code></p>

<a name=.un></a>
<h3><code>.un(obj)</code></h3>
<p><b>Instance method</b></p>
<p>
    <b>Parameters:</b><br />
    <span class=parameters>obj</span> - <code>object</code>
</p>
<p><b>Returns: </b><code>undefined</code></p>
<p>Convenience method for unregistering listeners with a common scope.
    Internally, this method calls <code>this.unregister</code> as shown in the examples below.</p>
<p>Examples:</p>
<pre><code>&nbsp;&nbsp;&nbsp;&nbsp;// unregister a single listener for the "loadstart" event
    events.un({"loadstart": loadStartListener});
    
    // this is equivalent to the following
    events.unregister("loadstart", undefined, loadStartListener);
    
    // unregister multiple listeners with the same `this` object
    events.un({
        "loadstart": loadStartListener,
        "loadend": loadEndListener,
        scope: object
    });
    
    // this is equivalent to the following
    events.unregister("loadstart", object, loadStartListener);
    events.unregister("loadend", object, loadEndListener);
</code></pre>

<a name=.remove></a>
<h3><code>.remove(type)</code></h3>
<p><b>Instance method</b></p>
<p>
    <b>Parameters:</b><br />
    <span class=parameters>type</span> - <code>string</code>, name of event
</p>
<p><b>Returns: </b><code>undefined</code></p>
<p>Remove all listeners for a given event type. If type is not registered, does nothing.</p>

<a name=.triggerEvent></a>
<h3><code>.triggerEvent(type, event)</code></h3>
<p><b>Instance method</b></p>
<p>
    <b>Parameters:</b><br />
    <span class=parameters>type</span> - <code>string</code>, name of event<br />
    <span class=parameters>event</span> - <code>object</code>, event object
</p>
<p><b>Returns: </b><code>boolean</code></p>
<p>Trigger a specified registered event.
    If a listener returns false, the chain of listeners will stop getting called.</p>

<a name=.clearMouseCache></a>
<h3><code>.clearMouseCache()</code></h3>
<p><b>Instance method</b></p>
<p>
    <b>Parameters:</b>
</p>
<p><b>Returns: </b><code>undefined</code></p>
<p> Clear cached data about the mouse position.
    This should be called any time the element that events are registered on changes position within the page.</p>

</div>

</body>
</html>
